Fanbook SDK集成文档(iOS)
概述#
FanBookSDK 提供了 FanBook 的授权、分享以及打开 FanBook 圈子的能力。
环境#
Xcode版本：Xcode7 或以上 系统版本：iOS 9.0 或以上
资源#
1. 向FanBook注册您的应用程序，#
请到开发者平台 应用管理页面 创建应用。创建完成并选择新建的应用，将获得clientID，可立即用于开发。
2. SDK下载#
SDK 仅包含一个FanBookSDK.framework文件，请点击 FanBookSDK下载 获取最新 SDK。
集成FanBook到项目中#
1. 添加 SDK 资源到项目中#
将 FanBookSDK.framework、fanbookSDK.bundle 文件添加到你所建的工程中（如下图所示）
2. 添加 framework 文件路径#
选择 TARGETS –> Build Settings –> Framework Search Paths，在此添加FanBookSDK的framework文件路径。（支持相对路径和绝对路径，不可含有空格）
3. 检查 framework 的嵌入与签名方式#
选择 TARGETS –> General –> Framework, Libraries, and Embeded Content,检查是否包含FanBookSDK.framework，且嵌入方式为Do Not Embed
4. 设置 Build Settings#
选择 TARGETS –> Build Settings -> Linking -> Other Linker Flags，添加 -ObjC
5. URL Scheme 配置#
选择 TARGETS –> Info –> URLTypes，新增一条URL scheme，命名为fanbook+bundleID+clientId，bundleID去掉"." ，例如: 若bundleID为"com.idreamsky.fbapp"，clientId为"123456789"，则最终的URL scheme为 "fanbookcomidreamskyfbapp123456789"
6. LSApplicationQueriesSchemes 配置#
选择 TARGETS –> Info –> LSApplicationQueriesSchemes，添加以下内容：
<key>LSApplicationQueriesSchemes</key> <array> <string>fanbook</string> </array>回调处理#
授权功能会拉起FanBook的客户端APP进行操作。FanBook客户端在操作完成之后，会调回信息到APP，APP需要处理这个回调，从而获得FanBook客户端的操作结果。
1. 导入头文件#
在你需要使 FanBookSDK API 的文件中 import FanBookApi.h 头文件，并增加 FanBookApiDelegate 协议。
#import <FanBookSDK/FanBookApi.h>
@interface AppDelegate ()<FanBookApiDelegate>
@end2. 转发回调信息到FanBookSDK#
重写 AppDelegate 的 openURL 方法，并将上述方法中的 url 转发给 FanBookSDK
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{ [FanBookApi handleOpenURL:url delegate:self];
return YES;}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{ [FanBookApi handleOpenURL:url delegate:self];
return YES;}注意：适配了 SceneDelegate 的 App，系统将会回调 SceneDelegate 的 openURLContexts 方法，所以需要重写 SceneDelegate 中的该方法。
#pragma mark - System Integration
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts{ UIOpenURLContext *urlContext = URLContexts.allObjects.firstObject; if (nil != urlContext) { [FanBookApi handleOpenURL:urlContext.URL delegate:self]; }}3. 实现FanBookSDK代理回调方法#
注意 onResp 代理方法的实现应该与您调用FanBookSDK 的 handleOpenURL 方法处在同一个类文件中，且只有调用了 handleOpenURL 方法才会触发代理方法的回调。
#pragma mark - FanBookApiDelegate
- (void)onResp:(FanBookBaseResp *)resp{ if ([resp isKindOfClass:[FanBookSendAuthResp class]]) { FanBookSendAuthResp *authResp = (FanBookSendAuthResp *)resp; if (FanBookSuccess == authResp.errCode) { // 授权成功 NSString *code = authResp.code; // 授权码 } else { // 授权失败 } } }API#
1. 注册 SDK#
简要描述： 需要在你的程序启动后在代码中向FanBookSDK注册你的 clientId。开发者需要配合使用 FanBook 开放平台提供的 CLIENT ID 进行注册（在 AppDelegate 的 didFinishLaunchingWithOptions 函数中向 FanBookSDK 注册），FanBookSDK 所有接口需要注册成功之后才可以调用。
函数原型:
/// FanBook SDK 注册+ (BOOL)registerApp:(NSString *)clientId;参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| clientId | NSString | 是 | 在 FanBook 应用管理详情页取得的 CLIENT ID |
返回值说明：
| 返回值类型 | 说明 |
|---|---|
| BOOL | 注册成功返回YES，失败返回NO |
示例：
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{ // 注册FanBookSDK [FanBookApi registerApp:@"your client id"]; return YES;}2. 获取 SDK 版本号#
函数原型:
/// 获取当前FanBook SDK的版本号+ (NSString *)getSDKVersion;返回值说明：
| 返回值类型 | 说明 |
|---|---|
| NSString | 当前 FanBook SDK 的版本号 |
示例：
NSString *version = [FanBookApi getSDKVersion];3. 检查FanBook客户端是否安装#
简要描述： 获取当前设备上是否已安装 FanBook 客户端 APP。
注意：
当 LSApplicationQueriesSchemes 配置不正确时，该接口可能无法返回正确的结果。
函数原型:
/// 检查FanBook是否已被用户安装+ (BOOL)isFanBookAppInstalled;返回值说明：
| 返回值类型 | 说明 |
|---|---|
| BOOL | 已安装返回YES，未安装返回NO。 |
示例：
if ([FanBookApi isFanBookAppInstalled]) { // FanBook已安装 } else { // FanBook尚未安装 }4. 打开FanBook圈子#
简要描述： 1.0.6版本已废弃
函数原型:
/// 打开FanBook圈子+ (BOOL)openFanBookZoneWithServiceID:(NSString *)serviceID channelID:(NSString *)channelID;参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| serviceID | NSString | 是 | FanBook 服务器 ID |
| channelID | NSString | 是 | FanBook Channel ID |
返回值说明：
| 返回值类型 | 说明 |
|---|---|
| BOOL | 打开成功返回YES，失败返回NO |
示例：
[FanBookApi openFanBookZoneWithServiceID:@"your service id" channelID:@"your channel id"];5. 打开网页#
简要描述： 在应用内使用 WKWebView 打开一个指定的网页链接，该 webView 方向固定向上，不随设备的翻转而变化。
函数原型:
/// 打开一个链接+ (void)openUrl:(NSString *)url;参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| url | NSString | 是 | 要打开的链接地址 |
返回值说明：
| 返回值类型 | 说明 |
|---|---|
| BOOL | 打开成功返回YES，失败返回NO |
示例：
[FanBookApi openUrl:@"https://fanbook.idreamsky.com"];6. 获取授权码#
简要描述： 开发者移动应用会在终端本地拉起 FanBook 应用进行授权，FanBook 用户确认后，FanBook 将拉起开发者移动应用，并带上授权临时票据（code）。
函数原型:
/// 发送请求到FanBook，等待FanBook返回后调用handleOpenURL方法，随后触发onResp代理函数，获取授权最终结果。+ (void)sendReq:(FanBookBaseReq *)req success:(FanBookSDKSuccess)succ fail:(FanBookSDKFail)fail;注意： 该函数中成功回调（FanBookSDKSuccess）与失败回调（FanBookSDKFail）仅代表本次授权请求发送是否成功，并不代表授权最终结果。最终的授权结果需要在调用 handleOpenURL 转发回调信息给 FanBookSDK 后触发的 onResp 代理回调方法中获得。
参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| guildId | NSString | 否 | 三方应用在 FanBook 后台申请的服务器Id |
| inviteCode | NSString | 否 | 服务器邀请码。当玩家不在官方服务器时，使用此邀请码邀请玩家加入。 |
| state | NSString | 否 | 用于保持请求和回调的状态，授权请求后原样带回给调用方。该参数可用于防止 srf 攻击（跨站请求伪造攻击），建议调用时带上该参数，可设置为简单的随机数或 UUID 大小不能超过1k |
回调函数声明：
typedef void (^FanBookSDKSuccess)(NSString *msg, __nullable id data);
typedef void (^FanBookSDKFail)(FanBookErrorCode code, NSString *msg, __nullable id errorData);回调参数说明：
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| code | FanBookErrorCode | 错误码 |
| msg | NSString | 状态详情描述 |
| errorData | id | 错误对象，通常为nil |
| data | id | 返回信息对象，通常为nil |
示例：
FanBookSendAuthReq *authReq = [[FanBookSendAuthReq alloc] init]; authReq.state = [[NSUUID UUID] UUIDString]; authReq.guildId = @"your guildId"; authReq.inviteCode = @"your inviteCode";
[FanBookApi sendReq:authReq success:^(NSString *_Nonnull msg, id _Nullable data) { // 发送FanBook授权请求成功 } fail:^(FanBookErrorCode code, NSString *_Nonnull msg, id _Nullable errorData) { // 发送FanBook授权请求失败 }];7. 分享#
简要描述： 开发者移动应用会在终端本地拉起 FanBook 应用进行分享，FanBook 用户确认后，FanBook 将拉起开发者移动应用。
函数原型:
/// 发送请求到FanBook+ (void)sendReq:(FanBookBaseReq *)req success:(FanBookSDKSuccess)succ fail:(FanBookSDKFail)fail;回调函数声明：
typedef void (^FanBookSDKSuccess)(NSString *msg, __nullable id data);
typedef void (^FanBookSDKFail)(FanBookErrorCode code, NSString *msg, __nullable id errorData);回调参数说明：
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| code | FanBookErrorCode | 错误码 |
| msg | NSString | 状态详情描述 |
| errorData | id | 错误对象，通常为nil |
| data | id | 返回信息对象，通常为nil |
7.1 分享图片#
参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| guildId | NSString | 是 | 三方应用在 FanBook 后台申请的服务器Id |
| inviteCode | NSString | 是 | 服务器邀请码。当玩家不在官方服务器时，使用此邀请码邀请玩家加入。 |
| image | NSData 或 NSString | 是 | 图片数据，如果是 NSData 类型，大小不能超过10MB，如果是网络图片地址（ NSString 类型），大小不能超过2k |
| desc | NSString | 否 | 描述字符串 |
示例：
FanbookShareImageReq *shareImageReq = [[FanbookShareImageReq alloc] init]; shareImageReq.image = imageData; shareImageReq.guildId = @"your guildId"; shareImageReq.inviteCode = @"your inviteCode"; shareImageReq.desc = @"your desc";
[FanBookApi sendReq:shareImageReq success:^(NSString *_Nonnull msg, id _Nullable data) { //发送FanBook分享图片请求成功 } fail:^(FanBookErrorCode code, NSString *_Nonnull msg, id _Nullable errorData) { // 发送FanBook分享图片请求失败 }];7.2 分享链接#
参数说明：
| 参数名称 | 参数类型 | 是否必传 | 说明 |
|---|---|---|---|
| guildId | NSString | 是 | 三方应用在 FanBook 后台申请的服务器Id |
| inviteCode | NSString | 是 | 服务器邀请码。当玩家不在官方服务器时，使用此邀请码邀请玩家加入。 |
| link | NSString | 是 | 链接url |
| image | NSData 或 NSString | 否 | 图片数据，如果是 NSData 类型，大小不能超过10MB，如果是网络图片地址（ NSString 类型），大小不能超过2k |
| desc | NSString | 否 | 描述字符串 |
示例：
FanbookShareLinkReq *shareLinkReq = [[FanbookShareLinkReq alloc] init];
shareLinkReq.guildId = @"your guildId"; shareLinkReq.inviteCode = @"your inviteCode"; shareLinkReq.link = @"your link"; shareLinkReq.image = imageData; shareLinkReq.desc = @"your desc";
[FanBookApi sendReq:shareLinkReq success:^(NSString *_Nonnull msg, id _Nullable data) { //发送FanBook分享链接请求成功 } fail:^(FanBookErrorCode code, NSString *_Nonnull msg, id _Nullable errorData) { // 发送FanBook分享链接请求失败 }];8. 打开FanBook APP#
简要描述： 打开FanBook APP
函数原型:
+ (void)openFanBookApp:(nullable NSDictionary *)args completion:(void (^__nullable)(BOOL success))completion;参数args字段说明：
| 参数名 | 参数类型 | 是否必传 | 说明 | 备注 |
|---|---|---|---|---|
| url | String | 否 | 邀请链接 | 打开FanbookApp后会自动跳转到该服务器和频道(如果未加入服务器会邀请加入) |
示例：
///打开频道[FanBookApi openFanBookApp:@{@"url":@"https://fanbook.mobi/m5MMAFrZ"} completion:nil];
///打开直播[FanBookApi openFanBookApp:@{@"url":@"https://fanbook.mobi/live?roomid=461822646359953408&guildId=291937401222201344&channelId=303816216542183424&jump=https%3A%2F%2Ffanbook.mobi%2F4B33AFGE"} completion:nil];
错误码#
| 错误码标识 | 错误码 | 描述 |
|---|---|---|
| FanBookSuccess | 0 | 成功 |
| FanBookErrorCodeCommon | -1 | 普通错误类型 |
| FanBookErrorCodeUserCancel | -2 | 用户点击取消并返回 |
| FanBookErrorCodeSentFail | -3 | 发送失败 |
| FanBookErrorCodeAuthDeny | -4 | 授权失败 |
| FanBookErrorCodeUnsupport | -5 | FanBook 不支持 |
| FanBookErrorCodeUnknown | -10000 | 未知错误 |
| FanBookErrorCodeUninstalled | -10001 | FanBook 未安装 |
| FanBookErrorCodeParameterError | -10003 | 参数缺失或参数错误 |
| FanBookErrorCodeInitError | -10004 | 尚未初始化或初始化失败 |